home *** CD-ROM | disk | FTP | other *** search
/ Mac OS 9 Serial Number Archive / SN Archive 2023.11.04.toast / BSNG / SDK / BSNG SDK 1.0.3 / BSNG API.h next >
Encoding:
C/C++ Source or Header  |  1997-10-29  |  11.1 KB  |  196 lines  |  [TEXT/CWIE]
  1. /*
  2.  * $Workfile:: BSNG API.h                                                     $
  3.  * $Revision:: 3                                                              $
  4.  *
  5.  * $Author:: Buck Rogers                                                      $
  6.  * $Modtime:: 29.10.1997 16:00 Uhr                                            $
  7.  *
  8.  * $History:: BSNG API.h                                                      $
  9.  * 
  10.  * *****************  Version 3  *****************
  11.  * User: Buck Rogers  Date: 29.10.1997   Time: 16:01 Uhr
  12.  * Updated in $/BSNG/Plugins/BSNG SDK
  13.  * added errorText to display custom error messages
  14.  * 
  15.  * *****************  Version 2  *****************
  16.  * User: Buck Rogers  Date: 05.10.1997   Time: 19:12 Uhr
  17.  * Updated in $/BSNG/Plugins/BSNG SDK
  18.  * Added name, company and number of copies items that contain the default
  19.  * values set in the BSNG App preferences
  20.  * 
  21.  * *****************  Version 1  *****************
  22.  * User: Buck Rogers  Date: 30.09.1997   Time: 18:31 Uhr
  23.  * Created in $/BSNG/Plugins/BSNG SDK
  24.  * Adding subproject 'BSNG' to '$/'
  25.  *
  26.  * $NoKeywords::                                                              $
  27.  */
  28.  
  29.  
  30. #pragma once
  31.  
  32.  
  33. #if PRAGMA_ALIGN_SUPPORTED
  34. #pragma options align=mac68k
  35. #endif
  36.  
  37. /*
  38.     These are the IDs of the 10 LGAEditField you can use.
  39.     MAKE SURE THAT EVERY LGAEditField YOU ADD TO YOUR LAYOUT IS WITHIN THAT RANGE!!!
  40.     
  41.     Note:    The only items that need special ID and/or message ranges are:
  42.             LGAEditFields (ID range: between kEditItem1 = 100001 to kEditItem10 = 100010)
  43.             LGAPushButtons (ID and message range: between 300000 and 399999)
  44.     
  45.     Everything else you add, like LGACaptions or LGAFocusBorders should have an ID smaller than 100000 though to
  46.     avoid possible conflicts with the BSNG App in the future.
  47. */
  48.  
  49. enum EditFieldItem        {kEditItem1 = 100001, kEditItem2 = 100002, kEditItem3 = 100003, kEditItem4 = 100004, kEditItem5 = 100005,
  50.                          kEditItem6 = 100006, kEditItem7 = 100007, kEditItem8 = 100008, kEditItem9 = 100009, kEditItem10 = 100010};    
  51.  
  52. /*
  53.     These are values you can use to access the itemValue array. If you want to access the value the user entered in your
  54.     LGAEditField with the ID kEditItem2 you can use itemValue[1] or for more readability itemValue[kItemValue2]
  55. */
  56.  
  57. enum EditFieldValue        {kItemValue1 = 0, kItemValue2 = 1, kItemValue3 = 2, kItemValue4 = 3, kItemValue5 = 4,
  58.                          kItemValue6 = 5, kItemValue7 = 6, kItemValue8 = 7, kItemValue9 = 8, kItemValue10 = 9};
  59.  
  60. /*
  61.     Here are the descriptions of all the possible messages your plugin can recieve:
  62.  
  63.     msgExtInit                 Will be passed when your plugin gets loaded.
  64.                             This is the time to set the 'wantsRandomButton' and 'canAddToSNList' values and to initialize your
  65.                             global variables. You should also load all additional resources (if you use any in your plug) that
  66.                             are needed for your calculations, like CRC tables etc., at this point of time.
  67.                             If your initialisation failed for some reason report that back to the BSNG App by setting 'error'
  68.                             to errExtInitFailed, if your init was successful set 'error' to errExtNoErr
  69.     
  70.     msgExtCalcHit            Will be passed when the user pressed the 'Calculate' button in the BSNG App.
  71.                             You should validate all necessary data for your calculations (passed to you in the 'itemValue' array)
  72.                             before you start calculating. set 'error' to errExtIncorrectValue with the corresponding
  73.                             EditFieldItem in 'errorInItem' back to the BSNG App if the validation failed.
  74.                             If the validation was succesful start your calculation and pass the result back in the appropiate entry
  75.                             in the 'itemValue' array (e.g. use itemValue[kItemValue2] if your output LGAEditField has the ID kEditItem2,
  76.                             use itemValue[kItemValue3] if your output LGAEditField has the ID kEditItem3 etc).
  77.     
  78.     msgExtRandomHit            You will only receive that message if you set 'wantsRandomButton' to true at Init time.
  79.                             Create a random serial number not dependent on user input and fill in all the necessary data into the
  80.                             'itemValue' array to display your calculations (see msgExtCalcHit how to do that)
  81.     
  82.     msgExtItemHit            You will receive that message only when you added one or more LGAPushButtons to your layout.
  83.                             The LGAPushButton IDs and messages have to be between 300000 and 399999 to make this work. The message
  84.                             of the LGAPushButton that was pressed will be passed to you in 'itemMessage'.
  85.                             You can do lots of things with this feature, like display your own about box, play a sound or whatever
  86.                             else comes to your mind. Actually this is very powerful because you get all control you need to
  87.                             'customize' your plugin, but please keep in mind not to 'bloat' your plugin by adding too much fancy stuff.
  88.                             All the values you probably changed for some reason in the 'itemValue' array will be displayed to the user
  89.                             when the BSNG App gets control again. Have fun :-)
  90.                             
  91.     
  92.     msgExtCreateRandom        Your plugin will only get this message if you set 'canAddToSNList' to true at Init time.
  93.                             Use the 'outputRefNum' to write your randomly calculated serial numbers to the filestream.
  94.                             Use FSWrite and/or the helper functions myOutputPStr, myOutputSuffixedPStr, myOutputText
  95.                             and myOutputSuffixedText from "standard utils" (included with this package) to write to the filestream.
  96.                             You should calculate 'numOfListNumbers' random numbers if you can and write them to the stream...
  97.                                 
  98.     msgExtCleanup            Will be passed when your plugin gets unloaded.
  99.                             All memory allocations you made at Init time or whenever and all the resources you loaded should be
  100.                             deallocated/freed/dissposed when your plugin receives this message to avoid memory leaks.
  101. */ 
  102.  
  103.  
  104. enum ExternalMessage    {msgExtInit = 1, msgExtCalcHit = 2, msgExtRandomHit = 3, msgExtItemHit = 4, msgExtCreateRandom = 5, msgExtCleanup = 6};
  105.  
  106. /*
  107.     Here are the descriptions of all supported errors at the moment. If you pass another value back to the BSNG App than those
  108.     listed here the user will be prompted with an 'the plugin reported an unknown error, please continue with caution' alert
  109.     
  110.     errExtInitFailed        Your plugin failed to initialize itself at Init time
  111.     
  112.     errExtIncorrectValue    report that error at msgExtCalcHit time if the user entered an incorrect value into one of the LGAEditField.
  113.                             Report the field containing the error back to the BSNG App by setting 'errorInItem' to the
  114.                             corresponding LGAEditField ID (kEditItem1...kEditItem10)
  115.     
  116.     errExtWritingToList        report that error when you got the msgExtCreateRandom message and for one or the other reason can't
  117.                             write your data to the list. If you report that error the creation of the complete list will be aborted.
  118.     
  119.     errExtNoErr                report this if everything works fine :-)
  120. */
  121.  
  122. enum ExternalError        {errExtInitFailed = -100000, errExtIncorrectValue = -100001, errExtWritingToList = -100002, errExtNoErr = 0};
  123.  
  124.  
  125. typedef struct
  126. {
  127.     short                theMessage;                /*    set by the BSNG App, you have to react to these messages */
  128.                                                 /*    (see ExternalMessage above) */
  129.     
  130.     unsigned long        itemMessage;            /*    if you added one or more LGAPushButtons (please only use LGAPushButtons, */
  131.                                                 /*    no other controls are supported yet) to your layout you find the message you */
  132.                                                 /*    configured for that LGAPushButton in here. LGAPushButton IDs and messages MUST be */
  133.                                                 /*    between 300000 and 399999 */
  134.     
  135.     Boolean                wantsRandomButton;        /*    set to true at Init time if your plugin can create random serial numbers */
  136.     
  137.     Boolean                canAddToSNList;            /*    set to true at Init time if your plugin can create numbers for the */
  138.                                                 /*    Random Serial Number List */
  139.     
  140.     Str63                name;                    /*    name, company and numCopies are default values entered in the BSNG App preferences. */
  141.     Str63                company;                /*    if possible copy these in values in the corresponding itemValue items at Init time */
  142.     Str15                numCopies;                /*    so that these values can appear as default in your generator. Also make sure that */
  143.                                                 /*    you make a serial number using these infos when the Serial Number List gets */
  144.                                                 /*    created (of course only if your plugin is a name-based algorithm) */
  145.     
  146.     unsigned short        numOfListNumbers;        /*    how many numbers to create for the random Serial Number List */
  147.     
  148.     short                outputRefNum;            /*    the reference number of the file to write to when we build the */
  149.                                                 /*    random Serial Number List */
  150.     
  151.     long                error;                    /*    if an error occured put the appropiate error number (see 'ExternalError' above) */
  152.                                                 /*    in here. You can create your own custom errors by setting this to a positive, */
  153.                                                 /*    non-zero value and putting your error text into the 'errorText' variable */
  154.                                                 
  155.     unsigned long        errorInItem;            /*    if the error that occured is of type 'errExtIncorrectValue' put the
  156.                                                 /*    appropiate 'EditFieldItem' in here. Lets say the wrong value is in itemValue[3] */
  157.                                                 /*    which is equal to itemValue[kItemValue4] put kEditItem4 into this field */
  158.     
  159.     unsigned long        randSeed1;                /*    set by the BSNG App, you can use these two randSeed values to initialize the */
  160.     unsigned long        randSeed2;                /*    Ultra Random Number Generator (source included) or any other Random Number Gen */
  161.     
  162.     unsigned long        appLaunchTime;            /*    set by the BSNG App, the time the BSNG App was launched in Ticks */
  163.     DateTimeRec            appLaunchDate;            /*    set by the BSNG App, the time the BSNG App was launched in a DateTimeRec */
  164.     
  165.     StringPtr            itemValue[10];            /*    You can add up to 10 LGAEditFields to your layout (please only use LGAEditFields, */
  166.                                                 /*    no other TextEdit fields are supported yet). The IDs of your LGAEditField MUST be
  167.                                                 /*    between 100001 and 100010 (kEditItem1...kEditItem10) */
  168.     
  169.     Str255                errorText;                /*    Whenever you signal an error in the 'error' variable you can make the BSNG app */
  170.                                                 /*    to display your own error text. Just put the string you want to show into this */
  171.                                                 /*    variable and the BSNG app will display it in an Alert. Your error text can be */
  172.                                                 /*    max. 255 characters long and has to be a pascal string. If you leave this string */
  173.                                                 /*    empty the BSNG app will display its own error alert as before. */
  174.                                                 /*    You can now also create your own error conditions, whenever you encounter an */
  175.                                                 /*    error other than those predefined set the 'error' variable to a positive, */
  176.                                                 /*    non-zero value and put the text you want to display into this variable */
  177.                                                 /*    Thanks to Mididman for suggesting this errorText variable */
  178. } BSNGParamBlock, *BSNGParamBlockPtr;
  179.  
  180.  
  181. /*
  182.     IMPORTANT!!! additional notes:
  183.     
  184.     You MUST create the following resouces, otherwise your plugin will not work:
  185.     
  186.     'cicn' ID 1000    must contain the icon displayed in the plugin list in the BSNG App
  187.     'STR ' ID 1000    must contain the text displayed under the icon, the max. supported length of this text is 27 characters
  188.     'PPob' ID 1000    must contain the layout displayed on the right side of the serial number generator window when your plugin
  189.                     gets selected. Use Metrowerks Constructor 2.4.2 or better (included in this distribution) to cusomize this view,
  190.                     but keep in mind what I told you about the LGAPushButtons and LGAEditFields earlier in this document.
  191. */
  192.  
  193. #if PRAGMA_ALIGN_SUPPORTED
  194. #pragma options align=reset
  195. #endif
  196.